home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat3 / Xm / XmClipboardStartCopy.z / XmClipboardStartCopy
Text File  |  1998-10-30  |  13KB  |  199 lines
  1.  
  2.  
  3.  
  4.      XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddSSSSttttaaaarrrrttttCCCCooooppppyyyy((((3333XXXX))))  UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV  XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddSSSSttttaaaarrrrttttCCCCooooppppyyyy((((3333XXXX))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.           XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddSSSSttttaaaarrrrttttCCCCooooppppyyyy - A clipboard function that sets up a
  10.           storage and data structure
  11.  
  12.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.           #include <Xm/CutPaste.h>
  14.           int XmClipboardStartCopy (_d_i_s_p_l_a_y, _w_i_n_d_o_w, _c_l_i_p__l_a_b_e_l,
  15.                   _t_i_m_e_s_t_a_m_p, _w_i_d_g_e_t, _c_a_l_l_b_a_c_k, _i_t_e_m__i_d)
  16.                   Display * _d_i_s_p_l_a_y;
  17.                   Window  _w_i_n_d_o_w;
  18.                   XmString        _c_l_i_p__l_a_b_e_l;
  19.                   Time    _t_i_m_e_s_t_a_m_p;
  20.                   Widget  _w_i_d_g_e_t;
  21.                   XmCutPasteProc  _c_a_l_l_b_a_c_k;
  22.                   long    * _i_t_e_m__i_d;
  23.           (vvvvooooiiiidddd)
  24.  
  25.      VVVVEEEERRRRSSSSIIIIOOOONNNN
  26.           This page documents Motif 2.1.
  27.  
  28.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  29.           XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddSSSSttttaaaarrrrttttCCCCooooppppyyyysets up storage and data structures to
  30.           receive clipboard data.  An application calls this function
  31.           during a cut or copy operation.  The data item that these
  32.           structures receive then becomes the next data item in the
  33.           clipboard.
  34.  
  35.           Copying a large piece of data to the clipboard can take a
  36.           long time.  It is possible that, once the data is copied, no
  37.           application will ever request that data. The Motif Toolkit
  38.           provides a mechanism so that an application does not need to
  39.           actually pass data to the clipboard until the data has been
  40.           requested by some application.
  41.  
  42.           Instead, the application passes format and length
  43.           information in XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddCCCCooooppppyyyy to the clipboard functions,
  44.           along with a widget ID and a callback function address that
  45.           is passed in XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddSSSSttttaaaarrrrttttCCCCooooppppyyyy. The widget ID is
  46.           necessary for communications between the clipboard functions
  47.           in the application that owns the data and the clipboard
  48.           functions in the application that requests the data.
  49.  
  50.           The callback functions are responsible for copying the
  51.           actual data to the clipboard through XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddCCCCooooppppyyyyBBBByyyyNNNNaaaammmmeeee.
  52.           The callback function is also called if the data item is
  53.           removed from the clipboard and the actual data is no longer
  54.           needed.
  55.  
  56.           _d_i_s_p_l_a_y   Specifies a pointer to the DDDDiiiissssppppllllaaaayyyy structure that
  57.                     was returned in a previous call to XXXXOOOOppppeeeennnnDDDDiiiissssppppllllaaaayyyy or
  58.                     XXXXttttDDDDiiiissssppppllllaaaayyyy.
  59.  
  60.  
  61.  
  62.  
  63.      Page 1                                         (printed 10/24/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddSSSSttttaaaarrrrttttCCCCooooppppyyyy((((3333XXXX))))  UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV  XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddSSSSttttaaaarrrrttttCCCCooooppppyyyy((((3333XXXX))))
  71.  
  72.  
  73.  
  74.           _w_i_n_d_o_w    Specifies the window ID of a widget that relates
  75.                     the application window to the clipboard. The
  76.                     widget's window ID can be obtained through
  77.                     XXXXttttWWWWiiiinnnnddddoooowwww.  The same application instance should
  78.                     pass the same window ID to each of the clipboard
  79.                     functions that it calls.
  80.  
  81.           _c_l_i_p__l_a_b_e_l
  82.                     Specifies the label to be associated with the data
  83.                     item.  This argument is used to identify the data
  84.                     item, as in a clipboard viewer.  An example of a
  85.                     label is the name of the application that places
  86.                     the data in the clipboard.
  87.  
  88.           _t_i_m_e_s_t_a_m_p Specifies the time of the event that triggered the
  89.                     copy.  A valid timestamp must be supplied; it is
  90.                     not sufficient to use CCCCuuuurrrrrrrreeeennnnttttTTTTiiiimmmmeeee.
  91.  
  92.           _w_i_d_g_e_t    Specifies the ID of the widget that receives
  93.                     messages requesting data previously passed by
  94.                     name. This argument must be present in order to
  95.                     pass data by name. Any valid widget ID in your
  96.                     application can be used for this purpose and all
  97.                     the message handling is taken care of by the cut
  98.                     and paste functions.
  99.  
  100.           _c_a_l_l_b_a_c_k  Specifies the address of the callback function
  101.                     that is called when the clipboard needs data that
  102.                     was originally passed by name. This is also the
  103.                     callback to receive the _d_e_l_e_t_e message for items
  104.                     that were originally passed by name. This argument
  105.                     must be present in order to pass data by name.
  106.  
  107.           _i_t_e_m__i_d   Specifies the number assigned to this data item.
  108.                     The application uses this number in calls to
  109.                     XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddCCCCooooppppyyyy, XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddEEEEnnnnddddCCCCooooppppyyyy, and
  110.                     XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddCCCCaaaannnncccceeeellllCCCCooooppppyyyy.
  111.  
  112.           For more information on passing data by name, see
  113.           XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddCCCCooooppppyyyy(3) and XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddCCCCooooppppyyyyBBBByyyyNNNNaaaammmmeeee(3).
  114.  
  115.           The _w_i_d_g_e_t and _c_a_l_l_b_a_c_k arguments must be present in order
  116.           to pass data by name. The callback format is as follows:
  117.  
  118.           void (*_c_a_l_l_b_a_c_k) (_w_i_d_g_e_t, _d_a_t_a__i_d, _p_r_i_v_a_t_e, _r_e_a_s_o_n)
  119.                   Widget  _w_i_d_g_e_t;
  120.                   long    *_d_a_t_a__i_d;
  121.                   long    *_p_r_i_v_a_t_e;
  122.                   int     *_r_e_a_s_o_n;
  123.           (vvvvooooiiiidddd)
  124.  
  125.           _w_i_d_g_e_t    Specifies the ID of the widget passed to this
  126.  
  127.  
  128.  
  129.      Page 2                                         (printed 10/24/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddSSSSttttaaaarrrrttttCCCCooooppppyyyy((((3333XXXX))))  UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV  XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddSSSSttttaaaarrrrttttCCCCooooppppyyyy((((3333XXXX))))
  137.  
  138.  
  139.  
  140.                     function.
  141.  
  142.           _d_a_t_a__i_d   Specifies the identifying number returned by
  143.                     XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddCCCCooooppppyyyy, which identifies the pass-by-name
  144.                     data.
  145.  
  146.           _p_r_i_v_a_t_e   Specifies the private information passed to
  147.                     XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddCCCCooooppppyyyy.
  148.  
  149.           _r_e_a_s_o_n    Specifies the reason. XXXXmmmmCCCCRRRR____CCCCLLLLIIIIPPPPBBBBOOOOAAAARRRRDDDD____DDDDAAAATTTTAAAA____DDDDEEEELLLLEEEETTTTEEEEor
  150.                     XXXXmmmmCCCCRRRR____CCCCLLLLIIIIPPPPBBBBOOOOAAAARRRRDDDD____DDDDAAAATTTTAAAA____RRRREEEEQQQQUUUUEEEESSSSTTTTare the possible
  151.                     values.
  152.  
  153.      RRRREEEETTTTUUUURRRRNNNN
  154.           _X_m_C_l_i_p_b_o_a_r_d_S_u_c_c_e_s_s
  155.                     The function was successful.
  156.  
  157.           _X_m_C_l_i_p_b_o_a_r_d_L_o_c_k_e_d
  158.                     The function failed because the clipboard was
  159.                     locked by another application. The application can
  160.                     continue to call the function again with the same
  161.                     parameters until the lock goes away. This gives
  162.                     the application the opportunity to ask if the user
  163.                     wants to keep trying or to give up on the
  164.                     operation.
  165.  
  166.      RRRREEEELLLLAAAATTTTEEEEDDDD
  167.           XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddCCCCaaaannnncccceeeellllCCCCooooppppyyyy(3), XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddCCCCooooppppyyyy(3),
  168.           XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddCCCCooooppppyyyyBBBByyyyNNNNaaaammmmeeee(3), XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddEEEEnnnnddddCCCCooooppppyyyy(3),
  169.           XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddEEEEnnnnddddRRRReeeettttrrrriiiieeeevvvveeee(3), XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddIIIInnnnqqqquuuuiiiirrrreeeeCCCCoooouuuunnnntttt(3),
  170.           XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddIIIInnnnqqqquuuuiiiirrrreeeeFFFFoooorrrrmmmmaaaatttt(3), XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddIIIInnnnqqqquuuuiiiirrrreeeeLLLLeeeennnnggggtttthhhh(3),
  171.           XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddIIIInnnnqqqquuuuiiiirrrreeeePPPPeeeennnnddddiiiinnnnggggIIIItttteeeemmmmssss(3), XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddLLLLoooocccckkkk(3),
  172.           XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddRRRReeeeggggiiiisssstttteeeerrrrFFFFoooorrrrmmmmaaaatttt(3), XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddRRRReeeettttrrrriiiieeeevvvveeee(3),
  173.           XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddSSSSttttaaaarrrrttttRRRReeeettttrrrriiiieeeevvvveeee(3), XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddUUUUnnnnddddooooCCCCooooppppyyyy(3),
  174.           XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddUUUUnnnnlllloooocccckkkk(3), and XXXXmmmmCCCClllliiiippppbbbbooooaaaarrrrddddWWWWiiiitttthhhhddddrrrraaaawwwwFFFFoooorrrrmmmmaaaatttt(3).
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                                         (printed 10/24/98)
  196.  
  197.  
  198.  
  199.